• Introduction to LDAP – A brief introduction of the LDAP Protocol internals.
• Architectural Components – The Sametime architectural components for LDAP to give the reader an understanding of the architectural components.
• Sametime Settings & Customization – Covers Sametime configurations, sametime.ini settings, and customization, including using the StLdapcustomized Java class.
• Troubleshooting Sametime and LDAP - Problem and solution table, common LDAP errors, and how to fix them.

Table of Contents

Introduction to LDAP

• Directory
• Entries
• Distinguished Names
• Attributes and Values
• Object Classes
• Directory Schema
• LDAP Basic Operations
• Searching the Directory
• Binding the Directory

Architectural Components

• Sametime Services
• Architecture and Directory Modules
• Sametime LDAP Connections
• Authentication
• Sametime Internal ID
• StResolve Service Application

Sametime Settings and Customization

• LDAP Directory Settings
• • Connectivity
  • Basic Settings
  • Authentication Settings
  • Search Settings
  • Group Content Settings
• Multiple LDAP Servers
• Sametime.ini Parameters
• Keep Alive Interval Parameter
• Respray Interval Parameter
• MAX Connections Number Parameter
• Pending Maximum Parameter
• Pending Low Parameter
• Authentication Connection Encrypted Only Parameter
• LDAP Server Timeout Limit Parameter
• MAX Number of Results per Search Query Parameter
• MIN Number of Chars to Match Parameter
• Using the LDAP Customized Java Library
• Prerequisites
• Serviceability
• General Procedure for Using a Custom Java Class
• String Manipulation Using Java Customized LDAP Attributes Example
• Java Customized LDAP Search Filter Generation Example
• Useful Web Links
• Sametime LDAP new features

Troubleshooting Sametime and LDAP

• LDAP Server Hardware Consdierations
• Troubleshooting Common Performance-related Issues
• STAuthentication Trace Example
• STresolve Traces Example
• Notes Client, StResolve, and LDAP Performance
• Steps for Troubleshooting
• Common Sametime LDAP issues
• Debugging using Trace Files
• Common LDAP Error Codes
• Using Ldapsearch utility in the troubleshooting process
• Collecting pertinent information

Appendix

• Sametime LDAP Trace Files
• Links for Tuning LDAP Servers
• Collection of Useful Links
• Acknowledgements

IBM Sametime Wiki

Refer to the IBM Sametime Wiki for planning, installing, and administering IBM Sametime:

http://www-10.lotus.com/ldd/stwiki.nsf

Skills required

You are familiar with installing, configuring, and administering a IBM Sametime server, and you have a IBM Sametime community server configured
for use with an LDAP server. The article applies to IBM Sametime 8.5.x. based and Sametime 9 when noted.

Introduction to LDAP

The Lightweight Directory Access Protocol is the Internet standard protocol for directory access. It is a client-server protocol running over TCP/IP.

A directory in the LDAP world is similar to a dictionary in a sense that it enables systems and applications to look up a name and the information
associated with that name. An LDAP server is a directory server that provides access to its directory through an LDAP service.

Figure 1: Client-server model

LDAP provides a common interface to the back-end directory, whether a Domino, Microsoft or Tivoli directory or any other directory that supports
the LDAP service.

For the list of LDAP directories specifically tested by IBM, refer to the Sametime system requirements.

Directory

A directory is actually a database of objects laid out in hierarchical and logical structure, often called a tree. Given this model, each
entry in the tree may have only one direct parent entry and 0-N direct child entries. The single most top-level object in the directory is called
the root entry, and is exceptional in not having a parent entry. See Figure 2.

Figure 2: Directory entries

A directory is a tree of directory entries:

• An entry consists of a set of attributes.
• An attribute has a name (an attribute type or attribute description) and one or more values. The attributes are defined in a schema (see
  the Directory Schema section).
• Each entry has a unique identifier: a Distinguished Name (see the Distinguished Names section).

Entries

Directory entries typically represent objects from the real world. A typical entry may represent a person, group, network host, printer, or any other real or virtual object.

Each entry has to comply with the following requirements:

• Is uniquely identified by a Distinguished Name (DN).
• Is identified with a type, called an object class. For example, all person entries in the directory belong to the “Person” object class.
• May have a collection of attributes that describes its characteristics.

Distinguished Names

The DN is a string that identifies the entry, distinguishing it from any other entry in the directory.

LDAP guarantees the following:

• Each entry has a DN.
• No two entries in the directory have exactly the same DN.

The DN reflects the hierarchical position of the entry in relation to its parent entries, using an object attribute called the Relative Distinguished
Name, or RDN.

Each entry has an RDN that identifies it uniquely within the scope of its parent entry. For example, if my direct parent entry is “O=IBM.COM”
and my RDN is “UID=JSmith”, then my DN is “UID=JSmith,O=IBM.COM”. See Figure 3.

Figure 3: DN and RDN example

Attributes and Values

The characteristics of an entry are kept in attribute-value pairs. Attribute values are mostly alphanumeric strings, but may also be represented
as binary data. For example: SN=Smith, where SN (the surname) is the attribute name and Smith is the value.

An attribute may have a single value or multiple values. The RDN described above is an example of a single value attribute.

The examples below demonstrate the attributes of multiple values.

Example 1:

CN=John Doe

CN=John S Doe

CN=John Sametime Doe

Example 2:

cn=MyGroup,o=MyOrg

cn=MyGroup

Example 3:

uniqueMember=uid=John Doe,o=MyOrg

<p>uniqueMember=uid=Jane Doe,o=MyOrg

The member attribute in a group entry is a multi-value attribute. The object class described in the following section is another example of
a multi-value attribute.

Object Classes

Every entry is associated with a type, called an object class. The object class defines rules, such as which attributes are required for entries
of its type. An LDAP client can use the object class attribute in a search operation to specify that search results should be limited to entries
of that type only.

The object class is a multi-valued attribute of the entry.

One object class can be sub-classed from another, thereby inheriting its set of rules. Therefore, the objectClass attribute of an entry can
have multiple values, one from each superior class.

NOTE: The object classes are defined in the Directory scheme. (see the Directory Schema section)

The following example looks at the entry of a person. The object class attribute has three values: top, person, and organizationalPerson.

.

DN: uid=JSmith, o=ibm.com

objectClass: top

objectClass: person

objectClass: organizationalPerson

uid: JSMith

Directory Schema

Information about the structure of the entries and the attributes is called the schema. Another definition for a schema is a set of rules
configured for the directory. It describes the object classes, attribute types, syntaxes, how different attributes are compared (case sensitive,
etc.), the formats for storing values, and more. The schema is stored in the LDAP directory server as a normal entry that is searchable and readable.

Different LDAP server vendors may specify different rules for the default schema installation. Moreover, directory administrators can extend
the schema according to proprietary requirements.

For example, a new attribute can be added to the directory schema called “SametimeServer,” which describes the Sametime Home-Server/Cluster
of a user. A new object class “SametimePerson” can be inherited from the existing object class “organizationalPerson,” and the new class can
be configured to require the “SametimeServer” as a mandatory attribute with a single value constraint, as shown.

New Attribute: SametimeServer

New Object Class: SametimePerson

Inherited from: organizationalPerson

Requires: SametimeServer attribute, single value

LDAP Basic Operations

The LDAP RFC defines several LDAP operations. This article refers to the most common operations:

• Search


• Bind

Searching the Directory

The most common operation performed in LDAP is the search query. A search query consists of the following three basic parameters that determine
which entries are needed and which can be left out. A list of additional parameters follows.

Base DN

Base DN specifies the tree location where the search operation starts.

When the LDAP directory is searched, the query always searches downwards, based on the specified scope. The search is never upwards.

Scope

Scope specifies one of the following.

• Base – A lookup operation. Only a single entry described by the base DN is matched and nothing more.


• One level – The search “looks down” one level below the base DN and no further. This is similar to opening a folder in a file system and
  looking only at the direct elements inside the folder.


• Subtree – All child entries of the base DN are searched, whether direct or not, including the base DN itself.

Using Sametime, this is an example of using the Subtree scope notion.

• Scope for searching for a person: recursive


• Scope for searching for groups: recursive

NOTE: The 'recursive' string in Sametime means to search the entire sub-tree of directory entries, starting from the Base DN location.

Filter

Filter is a string with one or more rules for specifying which entries within the given scope should be retrieved and which should be left
out. Each rule consists of an attribute name, an attribute value, and an operator defining how the value should be compared. For example, (objectClass=organizationalPerson)
specifies
only person entries.

In another example, the filter:

(&(objectClass=person)(|(givenName=John)(mail=john*)))

When writing a search filter, one must use special syntax, including special characters that should be replaced with the appropriate Escape
sequence. You can learn more about search filters from RFC 2254 at http://www.ietf.org/rfc/rfc2254.txt.

Another useful source on search filter syntax considerations including an example:
http://msdn.microsoft.com/en-us/library/aa746475%28VS.85%29.aspx

Additional Search Parameters

A search operation also includes the following parameters:

• Attributes – A list of the attributes to be returned for each entry.

Note: The DN is not an attribute, so it is always returned for each entry.


• Time limit – The maximum time in seconds for the LDAP server side to process the search request.


• Size limit – The maximum number of entries returned in an LDAP response.

NOTE: Sametime has its own set of requirements and recommended values for these parameters.

Binding the Directory

The bind operation is sent by the client to provide its identity to the server. LDAP clients normally send a bind operation immediately after
establishing their connection with the LDAP server. The server can grant privileges to the client according to the supplied identity. Subsequent
operations sent on the connection, such as searching or deleting entries, are controlled by the server according to the client’s credentials.
A client can change its identity by rebinding on a pre-established connection.

There are different types of bind operations supported by the LDAP protocol. The most common are anonymous and simple bind, also known as
authenticated bind.

An anonymous bind is the easiest way to establish a connection with the LDAP server. However, the anonymous client will have limited access
to the directory when compared to authenticated clients.

Using a simple bind, a client can be authenticated on the LDAP server by providing its DN and password in plain text. The server verifies
that such a person exists in the directory and that the supplied password is correct.

The LDAP protocol does not encrypt the password. It is possible to encrypt the LDAP connection using SSL (TLS), which ensures that all data
between the client and server, including user passwords, is encrypted in both directions.

To encrypt passwords for Sametime, refer to the InfoCenter link:http://www-10.lotus.com/ldd/stwiki.nsf/xpDocViewer.xsp?lookupName=Administering+Sametime+9.0+documentation#action=openDocument&res_title=Connecting_Sametime_to_the_LDAP_server_st9&content=pdcontent&sa=true

Architectural Components

This section discusses Sametime core functionalities and services related to the LDAP server to help you understand the architectural components.

The
Sametime Server acts as an LDAP client when making a connection to the LDAP server and requests operations on the LDAP server through that connection.
In general, the Sametime Server uses two (of several) LDAP operations: search and bind.

The Sametime server sends an LDAP request to
the LDAP server on behalf of Sametime client side activities and regular flow to fulfill core Sametime services such as login to Sametime, searching for a user, and adding new contact to the buddy list.

Sametime Services

These Sametime Service Applications (SA) use the LDAP directory to provide a service:

• StUsers - Logs in users via authentication, password, or token.


• StDirectory - Allows users to receive the content of a public group, and provides Sametime directory browsing capabilities (disabled by
  default).


• StResolve - Supplies the resolve service, which resolves a user name into a unique user ID.


• Userinfo - Accesses the LDAP server to retrieve user-related details that should be displayed as the user's business card. Provides the business card feature to be displayed on the client side.


• StPolicy - Defines Sametime policies and assigns policies per group/user.
  Searches through the organization’s directory for groups to which a given user directly belongs and assigns a policy to the user.

Each of these service applications uses and invokes directory modules to access the directory and provide specific functionality.

This user guide only discusses the three first services—Stusers, StDirectory, and StResolve—in detail.

Architecture and Directory Modules

Sametime uses the LDAP protocol to access the directory for the following functionalities:

• Authentication
• Resolve
• Group contents
• Directory browsing
• Userinfo
• Policy

The scope of this user guide covers only the four first functionalities. Each of the four Sametime functionalities has a corresponding module
that implements its functionality.

Sametime modules are software library components whose inner implementation is hidden from the Sametime calling application. This approach
allows the Sametime Service Application (SA) to utilize a generic API, which is not dependent on the type of the back-end directory, whether
LDAP or Domino.

Figure 4: Sametime Directory Architecture, Sametime layout pre-8.5 version

Sametime uses software modules to access the database and directory. Modules come in two versions: Notes and LDAP. The idea is that server
applications need not worry about the specific type of back-end directory. An SA such as StUsers or StResolve uses the Sametime Directory API,
which is a well-defined set of functions. The module implements these functions to contact the directory.

In summary:

• Sametime Directory modules come in two versions: Notes and LDAP.
• Sametime Notes modules use the Notes API to access the Domino directory.
• Sametime LDAP modules use the LDAP protocol for the same functionality.

Sametime LDAP Connections

StAuthentication module opens two connections to the LDAP server by default:

• For the search operation
• For the bind operation

All other modules open a single connection to the LDAP server.

The ST_DB_LDAP_CONNECTIONS_NUMBER parameter allows you to increase the number of connections per Sametime module. See the Multiple LDAP Servers
section for more information about this parameter.

Authentication

As part of the login process, users first have to be authenticated by Sametime. There are two types of authentication requests in Sametime:
password and token.

Authentication by Password

• Resolves the name to a DN.
• Validates the password.
• Used by Sametime Connect Client by default to log in to Sametime.

Authentication by Token

• Looks up the user.
• Validates the token using the Notes DLL/Notes API.
• The token validation is not related to LDAP. It is done entirely by Domino.
• Enables Single Sign-on (SSO) – for example in a WAS-based environment.
• Used by meeting services and Notes Single Sign-on.

Authenticating by Password Procedure

The procedure for authenticating a user by password consists of the following steps.

1. Finding the Person



To find a person in the directory, Sametime first looks at the format of the name supplied for the search. If it looks like a DN, Sametime
finds it using a base-scope search. This kind of search is very efficient, since the LDAP server looks directly into a specific entry in the
tree. However, most users don’t know or remember their DN, so they provide some attribute such as the common name. In that case, Sametime issues
a search operation using base, scope, and filter from the configuration.





If the user is not found or more than one match is found, the authentication fails. If the entry is unique, Sametime proceeds with validating
the password.



2. Validating the Password



Once we have the DN, we can issue a bind request to the LDAP server on behalf of the user. The bind request includes the DN and the password.
The bind operation is performed on a different connection than the one used for searching, so the authentication module has two connections to
the LDAP server.

Sametime Internal ID

Each user that is successfully authenticated by Sametime gets an internal identifier that serves as a unique ID for the authenticated user.

By default, Sametime uses the LDAP DN value of a user as Sametime Internal ID .

However, any LDAP attribute of a person entry that has a unique value (e.g. email) can be defined as a Sametime internal ID.

The name of the LDAP attribute is defined in the StConfig.nsf LDAP document.
The attribute is set using the following settings:

People
The attribute of the person entry that defines the internal ID of a Sametime user: [ ]

Since by default the attribute in this setting is empty, Sametime uses the LDAP DN value of an authenticated user as the Sametime Internal
ID of this user.

Note that when Sametime internal ID is changed, Sametime namechange task should be run to convert the old Sametime internal ID of each user
to the new one.

In addition, if such a change is planned in advance, customers may contact IBM support to get the right directions and guidelines regarding
this major change.

StResolve Service Application

The StResolve service application has three main services:

• Resolves the given name to a Sametime ID
• Searches for user/group (quickfind)
• Gets user details (using email in the ST-STGW environment)

The StResolve application is commonly used when adding a user to the contact list on the client side.

The StResolve Service Application calls StResolve.dll to resolve a given user name to a user ID, or a given group name to a group ID.

Resolving a user is similar to the first step of authentication by password; however, the search filter and size limit may be different to
allow multiple matches.

The following examples demonstrate the differences between the search filter for authentication and search filter for resolving.

Search filter to use when resolving a user name to a distinguished name (authentication):

((objectclass=organizationalPerson)(|(mail=%s)(cn=%s)(uid=%s)))

Search filter for resolving person names:

((objectclass=organizationalPerson)(|(mail=%s*)(cn=%s*)(uid=%s*)))

The client application specifies the resolve options through the Resolve API. This includes options such as whether to search for people or
groups, and whether multiple matches may be returned.

Sametime Settings and Customization

This section discusses Sametime LDAP configuration settings and common Sametime ini parameter that can be used to optimize Sametime/LDAP interactions.
In addition, it details how to use the StLdapCustomized Java library class.

LDAP Directory Settings

You can specify settings that determine how IBM Sametime interoperates with the LDAP directory. These settings can be edited directly
via StConfig.nsf using Notes client, or via the Sametime Administration tool using a Web browser.

IBM recommends using the Administration tool by default and leaving Stconfig.nsf for more advanced use.

In addition to the Sametime LDAP Directory settings, consider the Domino Directory assistance (DA.nsf) settings for Web conferencing.

NOTE: It is important to ensure that there is a match between Sametime LDAP directory settings and the directory assistance properties.

For more information on directory assistance, refer to the Information center web link:

http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=/com.ibm.help.domino.admin.doc/DOC/H_HOW_DIRECTORY_ASSISTANCE_WORKS_OVER.html

LDAP directory settings can be broken down into these sections:

• Connectivity
• Basic settings
• Authentication settings
• Search settings
• Group content settings

For comprehensive information on the LDAP directory settings with examples and recommended values, click the URL for LDAP directory setting.

http://publib.boulder.ibm.com/infocenter/sametime/v8r0/index.jsp?topic=/com.ibm.help.sametime.imlu.doc/st_adm_ldap_dir_settings_r.html.

NOTE: Starting Sametime 8.5 Sametime administrator can change most of the LDAP configuration settings via the Sametime System Console.
For more information on LDAP setting via Sametime System Console refer to the following link
http://www-10.lotus.com/ldd/stwiki.nsf/xpDocViewer.xsp?lookupName=Administering+Sametime+Standard+8.5.2+documentation#action=openDocument&res_title=Sametime_prerequisite_Connecting_to_an_LDAP_server_st852&content=pdcontent

Connectivity

The connectivity settings let the administrator provide the IP address and ports that the Sametime server uses when connecting to the LDAP
server. It also allows specifying whether the Sametime server binds to the LDAP server as an anonymous or authenticated user.

These settings enable the Sametime server to connect to multiple LDAP servers and use SSL when connecting to the LDAP server.

The search order field specifies the order in which Sametime connects to multiple LDAP servers. Note that this field must start with a value
of '1' for the first LDAP document.

Figure 5: Example of connectivity settings

Basic Settings

The basic settings let the administrator specify the initial LDAP parameters required to conduct searches for people and groups in an LDAP
directory. Some of these parameters are also necessary for displaying the names of users in Sametime user interfaces.

The basic settings include parameters that specify the level of a directory from which a search begins, the scope of the search, and the attributes
of the LDAP directory entries that define person and group names.

Figure 6: Example of basic settings for people

Authentication Settings

The authentication settings ensure that Sametime users can be authenticated against entries in an LDAP directory. The administrator must specify
an LDAP search filter that can resolve a name provided by a user to a DN in an LDAP directory. The authentication settings also let the
administrator specify the field in the LDAP directory person entries that contains the name of each user's home Sametime server.

When an end-user tries to log on, each occurrence of “%s” is replaced with the supplied name to create the actual filter. This filter, together
with two settings from the basic section, “Where to start searching for people” and “Scope for searching for a person” determines how the search
for the user is conducted. There is a difference between the filter in authentication and the filter in resolve. In resolve, there is an asterisk
after the “%s”, which means,“Return all users whose names begin with the supplied name.”

Figure 7: Example of authentication settings

NOTE: IBM WebSphere Application Server and Domino Directory Assistance use similar search filter criteria for authentication.

Search Settings

The search setting lets the administrator specify the search filters required to resolve the names of people and groups of specific entries
in an LDAP directory.

The search filter for resolving peoples’ names is similar to the search filter in authentication, but used for a different purpose—searching
for other people. For example, an end-user wants to add people to his buddy list. The end-user should not have to remember the exact names of
the users to add. Therefore, the search filter is combined with an asterisk (*) after each %s.

The search filter for resolving group names is similar to that used for people, but adds public groups to the buddy list.

Figure 8: Example of search settings

Group Content Settings

The group contents setting let the administrator specify the attribute of a group entry that contains the names of group members. This attribute,
which is associated with an object class, specifies the names of the group members. For example, this attribute may contain a list of distinguished
names, with one DN for each group member.

The attribute is used by the group contents module.

You can use this attribute to specify the LDAP field that contains the list of group members.

Multiple LDAP Servers

Each LDAP server has its own configuration document, and each LDAP server is given a search order. Some operations, such as resolve, require
stepping though all the LDAP servers listed. Other operations are optimized to contact only the relevant directory.

When resolving a name, all LDAP servers are searched, since there is no indication of how to limit the search to a single LDAP. Once the entry
found, the search stops and the rest of the LDAP servers are not searched.

When resolving a DN, a specific LDAP server is accessed. For example, the figure below shows two configured LDAP servers. The base DN for
searching groups in LDAP Server 1 is o=ibm.com and in LDAP Server 2 it is o=lotus.com.

If the group contents are requested for cn=groupA,ou=groups,o=lotus.com, Sametime finds that this group can only be found in LDAP Server 2
because the right part of the DN matches the base DN of Server 2 and not Server 1; therefore, only LDAP Server 2 is searched, leaving LDAP Server
1 aside.

Figure 9: Multiple LDAP server example

When there are multiple LDAP servers, there is a configuration document for each LDAP server and the LDAP server host name (or IP address)
is used as the unique identifier for the configuration document. If two LDAP servers have the same name, you can use the operating system host’s
file to map between the LDAP server’s IP address and an alias associated with this IP address. The alias will be used as the LDAP server host
name in the configuration document.

Sametime.ini Parameters

Some configuration settings are not available in StConfig.nsf or the admin pages. The following INI flags may be specified in the [Directory]
section of sametime.ini.

Keep Alive Interval Parameter

ST_DB_LDAP_KEEPALIVE_INTERVAL

The KEEPALIVE parameter defines the duration (in minutes) to wait while keeping alive messages that are sent by the Sametime Community server
on idle LDAP connections. Its default value is set to 1 minute.

The KEEPALIVE is an LDAP-based dummy search message whose purpose is to avoid the LDAP server or any network device along the way between
the Sametime server and the LDAP server from closing idle connections.

This flag is needed in certain LDAP environments where the LDAP server abruptly closes or resets the LDAP connection between Sametime and
LDAP due to no traffic activities on this connection per interval of time set by the LDAP server. To avoid this situation, make sure that there is
consistent traffic over the connection by turning on the KEEPALIVE parameter.

Respray Interval Parameter

ST_DB_LDAP_RESPRAY_INTERVAL

The RESPRAY parameter defines how often (in minutes) the connection to the LDAP server should be dropped and then re-established.

This parameter is very useful in a load balanced LDAP environment, since it allows the Sametime server to drop the current connection and
reestablish a new connection when the LDAP server is non-responsive.

By default, the RESPRAY flag is disabled.

NOTE: In pre-8.5 versions of Sametime 8.5, the RESPRAY interval must be higher than the KEEPALIVE interval.

Bear in mind that the RESPRAY operation is an expensive resource task, and may impact performance in an environment where the RESPRAY intervals
are set to low values.

MAX Connections Number Parameter

ST_DB_LDAP_CONNECTIONS_NUMBER

The CONNECTIONS_NUMBER parameter increases the number of concurrent connections from the Sametime Server to the LDAP server(s) specified in
the StConfig.nsf per Sametime module. The default setting is set to one connection per module except for StAuthentication.dll, which has two
connections.

Considerations before increasing the value to greater than one:

• Assume that ST_DB_LDAP_CONNECTIONS_NUMBER=3. Note that a value of 3 means that the Sametime server creates 3*N connections to the LDAP
  server, where N stands for the number of Sametime components that have an open connection to the LDAP. In addition, meeting and Domino components
  are connected to LDAP so the overall number of connections is greater than 3*N.


• This setting should only be modified if requests are taking an exceptionally long time to process due to long processing queues AND there
  are plenty of resources available on the Sametime and LDAP servers.


• Increasing the value of this parameter increases the number of LDAP threads available to service the request and multiplies the resource
  requirements for each one of the Sametime LDAP modules.


• It is highly recommended to apply an available fix when increasing the ST_DB_LDAP_CONNECTIONS_NUMBER flag to be greater than one.

For more information, see the LDAP-related Improvements in Sametime 8.5 section.

Pending Maximum Parameter

ST_DB_LDAP_PENDING_MAX

The PENDING_MAX parameter defines the maximum number of LDAP requests that can be pending per connection in the pending queue. Note that each
connection is for a different type of request; whether search or bind.

Any Sametime service that connects to the LDAP server utilizes the MIN and MAX PENDING queue. For information on the MIN PENDING queue see
below.

A Pending Resolve Request is a request that has been sent to the LDAP Server. The request is considered pending until the Sametime server
receives a response from the LDAP server for that request. The Sametime server sends, at most, MAX PENDING Requests to the LDAP server.

After MAX Pending Requests are sent to the LDAP server on a particular connection, the Sametime server does not send any additional LDAP
requests on this connection until the Pending Queue Size drops to the ST_DB_LDAP_PENDING_LOW Pending Request queue size.

For versions prior to Sametime 8.5, the flag value is set to 10 by default.

In Sametime 8.5 and higher, the value of this flag is set to 60 by default.

Pending Low Parameter

ST_DB_LDAP_PENDING_LOW

This parameter is strongly linked to the ST_DB_LDAP_PENDING_MAX flag and to the request queuing feature of Sametime.

Once ST_DB_LDAP_PENDING_MAX is reached for a certain connection, new LDAP requests are not sent on this connection until the number of pending
operations drops to the value set by the ST_DB_LDAP_PENDING_LOW flag.

For versions prior to Sametime 8.5, the value of the flag is set to 5 by default.

In Sametime 8.5 and higher, the value of the flag is set to 30 by default.

Special consideration is required for the PENDING MAX/LOW flags.

As the PENDING MAX/LOW flags relate to each LDAP connection,
Sametime might be configured to work with multiple connections per Sametime module, and one connection may stop handling requests while other
connections are working well.

The MAX and MIN pending queue sizes are highly dependent upon many factors, such as the resources available
to the Sametime server process on the host machine, the resources available to the LDAP process on the LDAP server, the network latency between
the Sametime and LDAP servers, the types of generated searches, and so on. As a result, there is no golden number to guarantee the greatest efficiency
for all configurations.

By default, MAX and MIN are set to 10 and 5, respectively. However, advanced guidelines for optimizing LDAP configurations
generally recommend 60 and 30. IBM typically recommends a size of 120 and 100 for larger corporations with high-powered LDAP servers.

NOTE: If the MAX and MIN sizes for the Pending Queue are not set appropriately, it is possible to overwhelm or throttle the LDAP server
or artificially reduce the potential high throughput of LDAP requests sent by Sametime to the LDAP server.

Authentication Connection Encrypted Only Parameter

ST_DB_LDAP_SSL_ONLY_FOR_PASSWORDS

This flag is used for performance optimization when SSL is enabled in the configuration. Enabling this flag means that only the authentication
connection is SSL encrypted. Other LDAP connections such as authorize-resolve, resolve, browse, and group contents are clear-text (that is, non-encrypted
data).

LDAP Server Timeout Limit Parameter

ST_DB_LDAP_SSL_SERVER_TIMELIMT

The SERVER_TIMELIMIT parameter is the maximum time after which the LDAP server must send a response to the request even if it didn't complete
processing it.

NOTE: The LDAP server may be configured with a smaller limitation. In either case, the smaller of the two will be the actual time limit.
The default value is 600 seconds (10 minutes).

MAX Number of Results per Search Query Parameter

ST_DB_LDAP_MAX_RESULTS

The MAX_RESULTS parameter defines the maximum number of entries that can be returned in a single search when searching for people or groups.
The default value is 1000.

MIN Number of Chars to Match Parameter

ST_DB_LDAP_MIN_WILDCARD

This parameter indicates the minimum number of characters to match when searching the LDAP user using wildcards.

When trying to resolve a user or group with a name that is too short than that defined by the ST_DB_LDAP_MIN_WILDCARD flag, Sametime does
not search the LDAP server.

For more information on sametime.ini parameters related to the LDAP directory and other techniques for tweaking the Sametime server behavior,
refer to “Optimizing name Lookup Sametime server” http://www-10.lotus.com/ldd/stwiki.nsf/dx/Optimizing_Name_Lookup_Sametime_server

This link has several references to online technical notes and documentation on Sametime Server and directory fine-tuning to achieve optimal performance
and streamlined connections.

Using the LDAP Customized Java Library

Sametime administrators who are familiar with Java programming can write Java classes that provide greater control over how the Sametime server
conducts and generates user/group name searches in an LDAP directory.

The administrator should follow standard programming rules; for example, the class should return a string object or NULL, get parameters of
type string, etc.

There are two main uses for Java-customized LDAP features:

• Manipulation of Java-customized LDAP attributes string enables you to take one LDAP attribute and modify its contents. This can be applied
  to any of the LDAP attribute settings. Java code can also be used to combine and merge the values of multiple LDAP attributes.


• Generation of Java-customized LDAP search filters can dynamically generate search filters used by Sametime. This is a very powerful method
  that can optimize LDAP performance. The search filter syntax and attributes vary, depending on which given name value is being searched.

Customizing the Java library is intended for administrators with experience in coding Java.

Note that there is No support of package-qualified Java classes in the customized code on the server

Prerequisites

A custom version of Java is installed as part of the Sametime server installation. A Java development environment does not need to be installed
on the server; rather, thee development can be done on any workstation as long as the compiled code is compatible with the Sametime server's
version of Java. This can be determined by running the java -version command for the Java executable located in the ibm-jre folder
of the Domino server installation.

Example of a Sametime server 9 running on Redhat Box:

[vm22 ~]$ cd /opt/ibm/lotus/notes/90000/linux/ibm-jre/jre
[vm22 ~]$ /opt/ibm/lotus/notes/90000/linux/ibm-jre/jre java -version
java version "1.6.0_24"
OpenJDK Runtime Environment (IcedTea6 1.11.11) (rhel-1.61.1.11.11.el6_4-x86_64)
OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)

Example of Sametime server 9 running on Windows:

Serviceability

Starting Sametime version 8.5, running on the AIX platform, it fully supports the customized Java library functionalities

For Sametime 8.5.2 IFR1 based versions, it is best practice to apply latest Cumulative Hotfix pack availalbe via FixCentral to run with the latest available code fix.
You can contact Sametime support for more information on where to obtain them.

In addition, you can check IBM Fix Central web page for recent Hotfix related to the LDAP custom library: http://www-933.ibm.com/support/fixcentral/

To download an LDAP customized Java code sample, visit the link for using Java to customize Sametime LDAP settings:
http://www-10.lotus.com/ldd/stwiki.nsf/dx/Optimizing_Name_Lookup_Sametime_server

General Procedure for Using a Custom Java Class

To use a custom Java class to control the LDAP directory’s search behavior, administrators should follow these steps: (Windows running Sametime example)

1. Write the Java source code file. The specific source code the administrator writes to support customized LDAP searches is entirely dependent on the user name requirements
   of your environment. Use the code sample below as a reference to help write the Java class appropriate for your environment.


2. Compile the Java source code file to produce the Java class file. Note that the compiled code has to be compatible with the Sametime server's
   version of Java. This can be determined by running the java -version command line of the Java executable located in the ibm-jre folder
   of the Domino server installation.


3. Copy the compiled class file to the java subdirectory of the Sametime server installation directory. In a default Sametime
   server installation, the directory path for the class file is c:\Lotus\Domino\java.


4. Update the sametime.ini file.This step ensures that the Sametime Community Services class path and JVM location settings are configured appropriately for the environment.


5. Open the sametime.ini file. By default, it is located in the C:\Lotus\Domino directory.


6. In the [Config] section of the sametime.ini file, make sure the ST_JAVA_CLASS_PATH parameter specifies the java subdirectory
   of the Sametime server installation directory (by default, C:\Lotus\Domino\java), as shown:
   
   ST_JAVA_CLASS_PATH=C:\Lotus\Domino\StConfig.jar;C:\Lotus\Domino\StConfigXml.jar;C:\Lotus\Domino\xerces.jar;C:\Lotus\Domino\java


7. In the [Config] section of the sametime.ini file, make sure the ST_JAVA_JVM_PATH parameter specifies the directory path to the jvm.dll
   file on the Sametime Server that is used by the Meeting Services. The recommended setting for the ST_JAVA_JVM_PATH parameter is ST_JAVA_JVM_PATH=C:\Lotus\Domino\ibm-jre\jre\bin\classic\jvm.dll


8. Save and close the sametime.ini file.


9. In the LDAP directory settings of the Sametime Administration Tool or the StConfig.nsf LDAP document, use the format Classname.methodname()
   to enter the Java class name and method name. Do not forget to add the necessary parameters between the parentheses.

You can use the Java code examples below as a reference.

String Manipulation Using Java Customized LDAP Attributes Example

The Display Name attribute is a common use for Java-customized LDAP attributes.

In most environments, the value of The attribute of the person entry that defines the user's name setting can specify a common
LDAP directory attribute, such as cn (common name) or mail (e-mail address). When configured in this way, the search returns the value assigned to a user's cn or mail directory attribute, and displays this value in the Sametime client user interface.

Some environments may require LDAP directory searches to return a user name in a format that is not available in an LDAP directory entry attribute.
In this case, the administrator can write a Java class that manipulates information existing in the LDAP directory to produce the user name in
the desired format.

For example, a company may require a display name in the format Smith, John.

If the LDAP server contains John in the givenName attribute, and Smith in the sn attribute, Sametime can be configured to combine the two attributes into a single display name using a simple Java method:

public class StLdapCustomized {

public static String displayName(String givenName, String sn) {

String result = sn + " ," + givenName;

return result;

}

}

This Java code tells Sametime to query the LDAP server for two attributes—givenName and sn—and then call the displayName method to combine
the two attributes into a single one. The result of the method is the final display name as seen by end-users.

Enter the Java class and method name into Sametime via StConfig.nsf or the Sametime Administration tool.

StConfig.nsf Modifications

1. Open LDAP documents and modified the required entry to point to the customization code: Schema Settings/People.


2. This is the attribute of the person entry that defines the person's name: StLdapCustomized.displayName(givenName, sn)

Administration Tool Modifications

1. From the Sametime server home page, click the Administer the Server link to open the Sametime Administration Tool.


2. Choose LDAP Directory, Basics.


3. In the Search settings for server drop-down list, select the LDAP server that contains the LDAP directory for which you want
   to modify The attribute of the person entry that defines the user's name setting.


4. In The attribute of the person entry that defines the user's name, type the class name and method name in the following format:
   



StLdapCustomized.displayName(givenName, sn)




5. Click Update and restart the server for the change to take effect.

Java Customized LDAP Search Filter Generation Example

In some LDAP directory environments, the LDAP directory schema may be too complex to use a single static search filter to select user names
(or group names) from the LDAP directory.

If a single search filter is not adequate to resolve user name (or group name) searches, the administrator can write a Java class containing
a method that specifies exactly how directory searches are conducted. This Java class can invoke different LDAP search filters, depending on
the search criteria entered by the end-user. Writing a Java class can ensure that the search capability functions exactly as needed for a particular
directory schema.

For example, consider a company that migrates its corporate directory from native Domino to an LDAP directory. The LDAP directory has Domino-like attributes
names such as notesemail and notesid.

Two assumptions to consider for the following example:

• The notesid attribute value in the LDAP directory does not contain an email ampersand (@).


• The CN value does not have any slashes.

The example below demonstrates how to generate a dynamic search filter for resolving person names based on the username value and format that is given
as an input for the Java code.

public class StLdapCustomized

{

public static String peopleResolveFilter(String name) {

// prevent users from adding wildcards

if (name.lastIndexOf('*') != -1)

return null;

)

boolean atsign = name.indexOf('@') != -1;

boolean slash = name.indexOf('/') != -1;<br>

//LDAP Directory attribute value examples:

// notesemail -> John Smith/Paris@FR

// notesid -> CN=John Smith/OU=Sales/O=Sametime

// mail -> jsmith@domain.com

// if name looks like e-mail, and not as Notesid do // not search with wildcards

if (atsign && !slash)

return (&(objectclass=person)(mail= + name + ));

String notesfield = atsign ? notesemail :notesid;

// check that the input name has format of notesid.

if ( name.toLowerCase().startsWith(cn=) && slash )

return (&(objectclass=person)( + notesfield + = <br> + name + ));

// check that the input name has format of notesemail

if (atsign && slash)

return (&(objectclass=person)( + notesfield + = <br> + name + ));

// otherwise, search as CN with wildcard

return (&(objectclass=person)(cn= + name + *));

}

}

This Java code gets an input string containing the name to be resolved and calls the String peopleResolveFilter method to generate a search filter according to
the name input string format. The result of the method is a search filter string.

Enter the Java class and method name into Sametime via the StConfig.nsf or via the Sametime Administration tool.

StConfig.nsf Modifications

1. To point to the customization code, open the LDAP document and modify the Schema settings/Search Filters entry.


2. To resolve people’s names, use the StLdapCustomized. peopleResolveFilter() search filter.

Administration Tool Modifications

1. To open the Sametime Administration Tool, from the Sametime server home page, click the Administer the Server link.


2. Choose LDAP Directory | Searching.


3. In the Search settings for server drop-down list, select the LDAP server that contains the LDAP directory for which you want to modify
   the Search filter for resolving person names setting.


4. In the Search filter for resolving person names setting, type the class name and method name in the following format:
   StLdapCustomized. peopleResolveFilter().


5. For the change to take effect, click Update and restart the server.

Encoding Special Characters as part of the search filter generation

When Sametime administrator utilizes a Java CustomizedLdap library, admin must enforce certain encoding on the username string to be resolved.

Note that if the Java customize code does not escape special characters that are embedded in the username string, it may cause Sametime connection to LDAP to hang.

Consequently, Resolve request coming from the client side may not get a response from Sametime server side.

The encoding of special characters is done according to RFC2254 - "The String Representation of LDAP Search."

The character must be encoded as the backslash '\' character (ASCII 0x5c) followed by the two hexadecimal digits representing the ASCII value of the encoded character.
This escaping mechanism eliminates filter-parsing ambiguities and allows any filter that can be represented in LDAP
to be represented as a NULL-terminated string.

Example A:
string to resolve -> "John()"
encoded string -> "John\28\29"

Example B:
string to resolve -> "\Jane"
encoded string -> "\5cJane"

The following Java code demonstrates how to call the escaping method in the peopleResolveFilter java method:

public static String peopleResolveFilter(String name) {

// prevent users from adding their own wildcards

if (name.indexOf('*') != -1)

return null;

//call the escaping function to escaped the string name according to LDAP filter escaping

//criteria

name=escapeUserId(name);

// if name looks like e-mail, do not search with wildcards

if (name.indexOf('@') != -1)

return "(&(objectclass=person)(mail=" + name + "))";

// otherwise, search as CN with wildcard

return "(&(objectclass=person)(cn=" + name + "*))";

}

Useful Web Links

Sametime InfoCenter:
http://publib.boulder.ibm.com/infocenter/sametime/v7r5m1/index.jsp?topic=/com.ibm.help.sametime.imlu.doc/st_adm_ldap_customjava_t.html

Using Java to customize Sametime LDAP Settings:
http://www-10.lotus.com/ldd/stwiki.nsf/dx/Optimizing_Name_Lookup_Sametime_server

Sametime LDAP new features

The following LDAP features are available starting with Sametime 8.5.2.
New feature introduced in Sametime 9 are mentioned as such.

• Support for multiple LDAP connections.



You can enable this feature using the following flag in sametime.ini:




[Directory]

ST_DB_LDAP_CONNECTIONS_NUMBER = x





where x is set to higher than 1.



• Support for LDAP UUID binary attributes that are mapped to the Sametime internal ID.
• Support for binary attributes that are commonly used in Novel and Microsoft Active Directory
• Support StResolve domain black/white list (available starting 8.5.2).
  http://www-10.lotus.com/ldd/stwiki.nsf/xpDocViewer.xsp?lookupName=Administering+Sametime+9.0+documentation#action=openDocument&res_title=Excluding_certain_domains_from_user_and_group_directory_lookups_st9&content=pdcontent
• Support synchronous mode of bind request as part of user authentication task
  For more information refers to the following link: https://www-304.ibm.com/support/docview.wss?uid=swg21412095
• GSkit is upgraded to v8.0.14.
• TDS is upgraded to v6.3


• Optimized LDAP search for mail addresses in Sametime 9 http://www-10.lotus.com/ldd/stwiki.nsf/xpDocViewer.xsp?lookupName=Administering+Sametime+9.0+documentation#action=openDocument&res_title=Disabling_optimized_user_searches_in_an_LDAP_directory_st9&content=pdcontent
• Diagnostics enhancements for Sametime 9 Community server directory applications. http://www-10.lotus.com/ldd/stwiki.nsf/xpDocViewer.xsp?lookupName=Administering+Sametime+9.0+documentation#action=openDocument&res_title=Disabling_optimized_user_searches_in_an_LDAP_directory_st9&content=pdcontent
• LDAP TLS configuration was enhanced in Sametime 9 HF1 as part of the generic TLS feature.
  http://www-10.lotus.com/ldd/stwiki.nsf/xpDocViewer.xsp?lookupName=Administering+Sametime+9.0+documentation#action=openDocument&res_title=Setting_up_TLS_configuration_st9&content=pdcontent




Troubleshooting Sametime and LDAP

---






LDAP Server Hardware Considerations




The following setup considerations are relevant and common to all LDAP servers, regardless of vendor type.

1. To utilize high performance, it is recommended that LDAP attributes that used in Sametime LDAP search filter should be indexed.
   For example, if Sametime search filter has the following syntax:
   ((objectclass=organizationalPerson)((mail=%s)(cn=%s)(uid=%s)),
   then mail, cn ,and uid LDAP attributes should be indexed on the LDAP server side.
   .


2. If name lookup fails or takes a long time, check that DNS is working or that DNS setup is properly configured.


3. Ensure that the disk subsystem is set up in a RAID array and run with RAID controllers. The supporting filesystems running on these disks
   should be laid out and tuned to optimize I/O transactions.


4. Tune the filesystem according to the operating system in use. For UNIX and Linux platforms, use a filesystem type that is better suited to the type of I/O patterns expected


5. The LDAP cache should be tuned to optimally use the available free memory.


6. Off load SSL encryption and decryption to improve performance.


7. Install latest patches to improve performance on LDAP server.


8. For large companies, put LDAP servers behind a load balancer.



Troubleshooting Common Performance-related Issues



1. In the Sametime.ini, in the [Debug] section, add the following flag:



[Debug]

VP_LDAP_TRACE=1




2. Restart StUsers.exe, StResolve.exe and StDirectory.exe.
3. Look in the StResolve, Stusers.exe and StDirectory.exe traces for repeat warning messages that appear consecutively in the logs for at least
   several minutes.



LDAP Resolve

08/Sep/09, 11:32:43 Warning:

10 operations waiting for response.

Will not request new operations until at most 5 are left.





This message indicates that the Sametime server is receiving a heavy load of requests and has to queue the requests for processing. In this
case, Sametime does not request new operations until there are five or fewer operations left.




In certain cases you should run a network sniffer to capture LDAP connection transactions in conjunction with Sametime traces.




To alleviate this problem, first you need to verify the number of allowed in-flight requests or to increase the processing capability of the
LDAP server. Alternatively, you may consider to increase the number of Sametime connections to the LDAP server to shorten the turnaround time.




In addition, you can get statistical data from the log files regarding the processing time for a request by identifying a user login or searching
events, and tracing the processing time that elapses between sending the request to the LDAP server and receiving a response.




STAuthentication Trace Example




131230_135251.328,INF,LDAP Aut,Starting authByPassword, context [-1] name [yafit] organization []

131230_135251.328,INF,LDAP Aut,Searching user, context [-1] name [yafit] directory [fox.haifa.ibm.com]

131230_135251.328,INF,LDAP Aut,---- Thread ID: 2616

131230_135251.328,INF,LDAP Aut,Searching, context [-1] connection [006A8078] base [dc=teamspace,dc=com] filter [(&(objectclass=organizationalPerson)(|(cn=yafit)(givenname=yafit)(sn=yafit)(mail=yafit)))] scope [Subtree]

131230_135251.328,INF,LDAP Aut,Search started, context [-1] connection [006A8078] msgId [23]

131230_135251.328,INF,ASYNC   ,---- Thread ID: 4768

131230_135251.328,INF,ASYNC   ,VpUsrAuthenticate::authenticateByPassword: pass to authentication BB reqId <0xffffffff>

131230_135251.328,INF,CRASH   ,VpUsrAuthenticate::authenticateByPassword: loginName <yafit>

131230_135251.328,INF,LDAP Aut,---- Thread ID: 1620

131230_135251.328,INF,LDAP Aut,Entry returned, DN [uid=yafit,cn=users,dc=teamspace,dc=com] context [-1] connection [006A8078] msgId [23] duration [0]

131230_135251.328,INF,LDAP Aut,Search success, name [yafit] context [-1] connection [006A8078] msgId [23] complete duration [0]

131230_135251.328,INF,LDAP Aut,---- Thread ID: 4696

131230_135251.328,INF,LDAP Aut,Binding, context [-1] connection [006A82F8] DN [uid=yafit,cn=users,dc=teamspace,dc=com]

131230_135251.328,INF,LDAP Aut,Bind started, context [-1] connection [006A82F8] msgId [23]

131230_135251.328,INF,LDAP Aut,---- Thread ID: 4144

131230_135251.328,INF,LDAP Aut,Bind success, user [yafit] context [-1] connection [006A82F8] msgId [23] complete duration [0]

131230_135251.328,INF,LDAP Aut,Async auth done. context [-1] code [0] user [uid=yafit,cn=users,dc=teamspace,dc=com] name [Prof. Yafit Sami] home [] organization []



1. User yafit sent a request to authenticate by password. It arrived at the StUsers service application at 13:52:51 on 30/12/2013.


2. The request to search yafit was sent to LDAP server fox.haifa.ibm.com at the same time

The entire processing time for user authentication by password is less than 1ms.

STresolve Traces Example

140128_111111.943,INF,LDAP Res,Starting resolve, context [-3117] name [baba] options [people/] organization []

140128_111111.943,INF,LDAP Res,---- Thread ID: 5776

140128_111111.943,INF,LDAP Res,Searching, context [-3117] connection [00698D38] base [dc=teamspace,dc=com] filter [(&(objectclass=organizationalPerson)(|(cn=baba*)(givenname=baba*)(sn=baba*)(mail=baba*)))] scope [Subtree]

140128_111111.943,INF,LDAP Res,Search started, context [-3117] connection [00698D38] msgId [193]

140128_111111.943,INF,Resolve ,---- Thread ID: 3324

140128_111111.943,INF,Resolve ,StResolveChannel::handleResolve: async continue

140128_111111.943,INF,Resolve ,StResolveChannel::handleResolve: sync continue onResolved

140128_111111.943,INF,LDAP Res,---- Thread ID: 5580

140128_111111.943,INF,LDAP Res,Entry returned, context [-3117] connection [00698D38] msgId [193] duration [0] DN [uid=Baba1,cn=users,dc=teamspace,dc=com] type [person] name [Baba1 Baba] desc [uid=Baba1,cn=users,dc=teamspace,dc=com] ID [uid=Baba1,cn=users,dc=teamspace,dc=com] org []

140128_111111.943,INF,LDAP Res,Entry returned, context [-3117] connection [00698D38] msgId [193] duration [0] DN [uid=Baba2,cn=users,dc=teamspace,dc=com] type [person] name [baba2 baba] desc [uid=Baba2,cn=users,dc=teamspace,dc=com] ID [uid=Baba2,cn=users,dc=teamspace,dc=com] org []

140128_111111.943,INF,LDAP Res,Entry returned, context [-3117] connection [00698D38] msgId [193] duration [0] DN [uid=Baba3,cn=users,dc=teamspace,dc=com] type [person] name [Baba3 baba] desc [uid=Baba3,cn=users,dc=teamspace,dc=com] ID [uid=Baba3,cn=users,dc=teamspace,dc=com] org []

140128_111111.959,INF,LDAP Res,Entry returned, context [-3117] connection [00698D38] msgId [193] duration [16] DN [uid=Baba4,cn=users,dc=teamspace,dc=com] type [person] name [Baba4 Baba] desc [uid=Baba4,cn=users,dc=teamspace,dc=com] ID [uid=Baba4,cn=users,dc=teamspace,dc=com] org []

140128_111111.959,INF,LDAP Res,Entry returned, context [-3117] connection [00698D38] msgId [193] duration [16] DN [uid=,cn=users,dc=teamspace,dc=com] type [person] name [ ] desc [uid=,cn=users,dc=teamspace,dc=com] ID [uid=,cn=users,dc=teamspace,dc=com] org []

140128_111111.959,INF,LDAP Res,Search returned, context [-3117] connection [00698D38] msgId [193] complete duration [16] result [0/Success] name [baba] state [1]

140128_111111.959,INF,LDAP Res,Resolve done, context [-3117] result [0]

The request to resolve user name baba got to the STresolve Service Application at 11:11:11 on 14/01/2014.

The request to search user baba is sent to LDAP server at 19:32:30 instanatly.

The search operation results of four matches returned from the LDAP server after 16 ms -> complete duration [16]

As a conclusion, the entire processing time till StResolve received all LDAP matches is 16 ms.

Note:
If search operations returning from LDAP server is consistently fast however if you find the corresponding Sametime request taking a long time
before being sent to the LDAP Server, the LDAP Server may be under utilized. ST_DB_LDAP_PENDING_MAX/LOW parameters will need to be reviewed
to maximize the number of search operations sent to the LDAP Server and minimize the wait before Sametime sends additional requests to the LDAP
Server.

Notes Client, StResolve, and LDAP Performance

Notes clients with Inbox awareness and QuickFind enabled generate an excessive number of name resolution requests every time the Notes user
changes pages. These resolve requests are processed via the Sametime STResolve server application that forwards the requests to the LDAP server
to get back a response.

Customers have encountered some or all of the following symptoms:

• User experience: QuickFind fails to search users.
• The STResolve process hangs and does not process further requests.
• The LDAP server becomes overloaded with requests.
• Excessive queuing occurs on the Sametime server.

Figure 11: Figure 11: Higher performance demand with Notes clients

Steps for Troubleshooting

There are server side and client side steps involved in the recommendations below for resolution. Note that it is up to the customer to choose
and implement the steps from both the server and the client perspective. Solutions and performance improvement results will defer from one
environment to another.

Server Side

• By reducing the number of LDAP attributes, the impact on the LDAP server and the search time is lower. Therefore, review all Sametime search filters to reduce the LDAP attributes that are included in the LDAP search filter.


• To prevent broad searches and searches that return too many results, set the STResolve service to require a minimum number of characters and
  a maximum number of results for searches. To use, implement the following settings in the sametime.ini on each server and restart the Sametime
  server.



[Directory]

ST_DB_LDAP_MIN_WILDCARD=<Minimum number of characters>

ST_DB_LDAP_MAX_RESULTS=<Maximum number of results>






NOTE: ST_DB_LDAP_MAX_RESULTS is set by default to return 1000 entries. It can be decreased to 100 as needed.



• Verify that the LDAP servers have sufficient processing capacity for the Sametime environment. Evaluate the traffic from other applications on the LDAP server. Monitor CPU
  and memory utilization.


• Update the sametime.ini flags as needed to optimize the connection to the LDAP server as explained in the Optimizing LDAP connections and queries on a Sametime server technote: http://www-10.lotus.com//ldd/stwiki.nsf/dx/Optimizing_Name_Lookup_LDAP_Directory_servers

Client Side

1. Disable public group expansion on the Notes Client via notes.ini.



IM_WATCH_PUBLIC_GROUPS =0.




May depend on corporate policy whether to apply these changes remotely.



2. Modify the Notes Mail templates to include a white list of resolvable domains.



This option is the preferred solution since it eliminates the generation of Resolve requests in the first place.




NOTE: This item is only for pre 8.x and 8.x basic Notes clients.




Title: Recommended Notes Modifications to reduce load on STResolve
Doc #: 1383203
URL: http://www.ibm.com/support/docview.wss?rs=899&uid=swg21383203

Deployment of a Notes Hotfix that contains a configurable filter for Internet email livename resolution. This is a plug-in (not a template design change)
for 8.x embedded Sametime clients only. Install this plug-in manually or via an SMS system. this is for 8.0.2 and 8.5 standard versions only]

See the links for LDAP server tuning for hardware considerations of the LDAP server and configuration recommendations.

Common Sametime LDAP issues

Debugging using Trace Files

The first step in troubleshooting problems is to collect the corresponding debug or trace data.

1. In the Sametime ini, set VP_LDAP_TRACE=1 to turn on tracing.


2. Delete any old contents of the trace folder: \Trace.


3. Enable Sametime to start writing trace messages. View Sametime LDAP Trace Files You don’t need to recycle the whole server. You can just restart the
   server application, which is ST Users for authentication or ST Resolve for resolve, and ST Directory. Each Sametime LDAP module prints debug messages to its own
   trace file into the Domino Install Directory\Trace folder. Note: Remember to disable the debug flag immediately after gathering trace
   files: VP_LDAP_TRACE=0


4. Cross-reference the configuration details in the trace file with the LDAP configuration data defined via the Web administration tool.


5. In the first run on a trace file, look for keywords such as “error”, “fail”, “unable”, “Warning”, ”timed out”, and exception. View Troubleshooting
   Common Performance-related Issues.

Common LDAP Error Codes

Using Ldapsearch utility in the troubleshooting process

Ldapsearch.exe is a built-in utility that is a part of the Domino server package.
It is an LDAP client that connects to a directory server and returns results that matches the
search criteria you specify. The utility is located in the same installation folder as Sametime.

Ldapsearch can be used in the troubleshooting process.
For example, when a Sametime process hangs or is slow to respond under a high load or a Resolve request,
you can check if the directory is alive using the ldapsearch utility to connect to the LDAP directory
and respond to an LDAP search query in a prompt manner.
This way, you can determine whether the issue is with Sametime or the LDAP server.

Usage Example 1

Search the root entry for the “namingcontexts” attribute:

ldapsearch -h bluepages.ibm.com -b -s base (objectclass=*) namingcontexts

Result:

namingcontexts=CN=SCHEMA

namingcontexts=OU=IBMDIRECTORIES,O=IBM.COM

namingcontexts=OU=IBMGROUPS,O=IBM.COM

namingcontexts=OU=BLUEPAGES,O=IBM.COM

namingcontexts=CN=LOCALHOST

Usage Example 2

Look for a specific person:

ldapsearch -h bluepages.ibm.com -b ou=bluepages,o=ibm.com -s subtree (&(objectclass=person)(John Doe))

Result:

DN: uid=549305756,c=il,ou=bluepages,o=ibm.com

...<list of attributes and values>...

While the LDAP server can respond immediately on some connections, other connections can be very slow and even hang. This is especially relevant for ldapsearch tests.
If ldapsearch returns immediately while the Sametime server is slow to respond, this is not decisive proof that there is a performance problem with the Sametime
server

Usually, the LDAP server simply can't handle the high load on a particular Sametime connection while performing an ldapsearch query that get
a respond within seconds.

For more information and examples of this utility, refer to Using the Ldapsearch utility:
http://publib.boulder.ibm.com/infocenter/domhelp/v8r0/index.jsp?topic=%2Fcom.ibm.help.domino.admin.doc%2FDOC%2FH_USING_LSEARCH_TO_SEARCH_A_DIRECTORY_7495_OVER.html

Collecting pertinent information

If you plan to contact IBM Sametime Support, please collect the following information before you call.

• Detailed use-case and scenario of the problem


• Exact time and date when the problem occurs


• Client type (Connect client, meeting, Notes client, etc.) and version


• \Trace folder


• IBM_TECHNICAL_SUPPORT folder under \Lotus\Domino\data folder on Windows


• sametime.log


• sametime.ini

Appendix

Sametime LDAP Trace Files

The trace file format name:

<Process_name>_<DDMMYY>_<HHMM>_<Process_Id>_<number of recycled_file>

The trace file name for the StUsers application:

StUsers_090710_1916_6668_000.txt

Trace file name for StAuthentication: (used by Stusers application)

StAuthentication_Stusers_090710_1916_6668_001.txt

Note that several different applications such as Meeting applications in addition to Sametime Stusers application use the authentication module
and use different names to distinguish the trace files of each application. Therefore, the trace file for authentication:


StAuthentication_<name_of_the_executable>_*.txt

Trace file name for StDirectory application:

StLdap_StDirectory_090805_1302_3172_000.txt

Trace file name for STResolve application and group contents:

StLdap_StDirectory_090805_1302_3172_000.txt
StLdap_StResolve_090811_1713_2392_002.txt

NOTE:
A trace file starts with printouts of the LDAP configuration parameters:

   1:  

   2:  090921_104617INF,LDAP Res,Initialization of configuration module completed successfully

   3:  

   4:  090921_104617INF,LDAP Res,Organization []

   5:  

   6:  090921_104617INF,LDAP Res,Host: [marketing.sales.acme.com[

   7:  

   8:  090921_104617INF,LDAP Res,Reading configuration of directory server marketing.sales.acme.com

   9:  

   10:  // LDAP server host name

   11:  

   12:  090921_104617INF,LDAP Res,host name: marketing.sales.acme.com

   13:  

   14:  // LDAP server port number

   15:  

   16:  090921_104617INF,LDAP Res,port: 389

   17:  

   18:  090921_104617INF,LDAP Res,ssl port: 636

   19:  

   20:  090921_104617INF,LDAP Res,ssl: disabled

   21:  

   22:  // Number of connections

   23:  

   24:  090921_104617INF,LDAP Res,connections: 1

   25:  

   26:  090921_104617INF,LDAP Res,alias dereferencing: 0

   27:  

   28:  090921_104617INF,LDAP Res,use internal proxy: no

   29:  

   30:  090921_104617INF,LDAP Res,Directory: [] [marketing.sales.acme.com]

   31:  

   32:  // Base object when searching for person entries

   33:  

   34:  090921_104617INF,LDAP Res,base dn for searching people:

   35:  

   36:  // Search filter for resolving persons name

   37:  

   38:  090921_104617INF,LDAP Res,filter for searching people:

   39:  (&(objectclass=organizationalPerson)(|(cn=%s*)(givenname=%s*)(sn=%s*)(mail=%s*)))

   40:  

   41:  // Search filter to use when resolving a user name to a distinguish name

   42:  

   43:  090921_104617INF,LDAP Res,filter for searching people by unique id:

   44:  (&(objectclass=organizationalPerson)(|(cn=%s)(givenname=%s)(sn=%s)(mail=%s)))

   45:  

   46:  // Scope for searching for a person : rescursive

   47:  

   48:  090921_104617INF,LDAP Res,scope for searching people: 2

   49:  

   50:  // Base object when searching for group entries

   51:  

   52:  090921_104617INF,LDAP Res,base dn for searching groups:

   53:  

   54:  // Search filter for resolving groups name

   55:  

   56:  090921_104617INF,LDAP Res,filter for searching groups:

   57:  (&(objectclass=groupOfNames)(cn=%*))

   58:  

   59:  // Scope for searching for groups : rescursive

   60:  

   61:  090921_104617INF,LDAP Res,scope for searching groups: 2

   62:  

   63:  // The attribute of the person entry that defines the internal ID of a Sametime user

   64:  

   65:  090921_104617INF,LDAP Res,user id attribute: DN

   66:  

   67:  // The attribute of the person entry that defines the person's name

   68:  

   69:  090921_104617INF,LDAP Res,persons name attribute: cn

   70:  

   71:  090921_104617INF,LDAP Res,persons desc attribute:

   72:  

   73:  // The attribute of the person entry that defines the group's name

   74:  

   75:  090921_104617INF,LDAP Res,groups name attribute: cn

   76:  

   77:  090921_104617INF,LDAP Res,groups desc attribute:

   78:  

   79:  // The group object class used to determine if an entry is a group

   80:  

   81:  090921_104617INF,LDAP Res,object class of a group entry: groupOfNames

   82:  

   83:  090921_104617INF,LDAP Res,object class of a person entry: organizationalPerson

   84:  

   85:  090921_104617INF,LDAP Res,home server attribute:

   86:  

   87:  // Attribute of the person entry that defined the person'email address

   88:  

   89:  090921_104617INF,LDAP Res,e-mail attribute: mail

   90:  

   91:  090921_104617INF,LDAP Res,maximum number of results: 1000

   92:  

   93:  090921_104617INF,LDAP Res,directory-wide search on DN: disabled

Links for Tuning LDAP Servers

Tuning Domino
http://www.ibm.com/developerworks/lotus/library/ls-perf_intro/

Tuning Tivoli directory server
http://www.redbooks.ibm.com/abstracts/redp4258.html

Tuning active directory
http://msdn.microsoft.com/en-us/library/windows/hardware/dn567654.aspx

Novell eDirectory tuning
http://www.novell.com/coolsolutions/feature/16117.html

Sun directory server

http://docs.oracle.com/cd/E19424-01/820-4812/gdrun/index.html

Tuning OpenLDAP
http://www.openldap.org/faq/data/cache/190.html

Collection of Useful Links

Following is a collection of useful links from this document:

Sametime LDAP directory settings:
http://publib.boulder.ibm.com/infocenter/sametime/v8r0/index.jsp?topic=/com.ibm.help.sametime.imlu.doc/st_adm_ldap_dir_settings_r.html

Optimizing LDAP connections and queries on a Sametime server:
http://www-10.lotus.com/ldd/stwiki.nsf/dx/Optimizing_Name_Lookup_Sametime_server

Using Java to customize Sametime LDAP settings:
http://www-10.lotus.com/ldd/stwiki.nsf/dx/Optimizing_Name_Lookup_Sametime_server#For+a+Sametime+server+configured+to+use+LDAP

Sametime 8.0.2.1 running on Linux:
http://www-01.ibm.com/support/docview.wss?rs=477&uid=swg21396511

A useful source on Search Filter Syntax considerations and example:
http://msdn.microsoft.com/en-us/library/aa746475%28VS.85%29.aspx

Sametime users unable to authenticate with Domino Canonical name:
http://www-01.ibm.com/support/docview.wss?rs=477&context=SSKTXQ&dc=DB520&dc=DB560&uid=swg21293951&loc=en_US&cs=UTF-8&lang=en&rss=ct477lotus